Synchronise

Synchronise(tag[, isasync[, up[, down]]])

Synchronise data between the mobile device and one or more Target ADO Database or Web API data sources.

All

tag - required

A name of your choice to identify this data synchronisation transaction.

The name you specify here will identify the transaction to the OnAsyncCompletion Event (see Notes below).

 

isasync - optional

Specifies whether you want the data transfer to take place in the background (asynchronously) or foreground (synchronously). It can take one of the following values:

 

up - optional

This parameter allows you to specify any Data Sources you want to upload from the device to the App Server to update your Target data sources.

You can explicitly specify the Data Sources you want to upload by specifying a comma-separated list of the relevant tables.

Alternatively, if you specify an empty string, "", the Method will upload all Data Source tables which have their Sync Direction Property set to Up or Both. This is the default value if this parameter is omitted.

If you don't want to upload any Data Sources, specify this parameter as Null.

The tables specified by this parameter can be different to those specified in the down parameter below.

 

See Notes below for more details.

 

down - optional

This parameter allows you to specify any Data Sources you want to be downloaded to the device from your Target data sources.

You can explicitly specify the Data Sources you want to download by specifying a comma separated list of the relevant tables.

Alternatively, if you specify an empty string, "", the Method will download all Data Source tables which have their Sync Direction Property set to Down or Both. This is the default value if this parameter is omitted.

If you don't want to download any Data Sources, specify this parameter as Null.

The tables specified by this parameter can be different to those specified in the up parameter above.

 

See Notes below for more details.

nothing

• Data records are marked as modified by calling UpdateCurrentRecord.

• For Web API Data Sources, you can only send one record at a time in the top-level request table. Child tables of this record can contain multiple records where a request parameter allows.

• This Method allows you to both download and upload data using a single Scripting Method. The data sources to be uploaded and downloaded are specified separately, allowing you to transfer data to and from the same or different data sources and to only transfer in one direction if required.

  It also allows you to choose whether data transfers should pause the Digitise app whilst transfers are in progress or perform transfers in background allowing users to continue to use the app whilst the transfers take place.

  It can only be used with remote database and Web API data sources although the local Data Source on the device can be an ADO Database Data Source or Custom Table, providing that with Custom Tables, the Data Source's Mode Property is set to Remote ADO. With Custom Tables data can only be downloaded to the device, you cannot upload data from a Custom Table.

• Unlike the LoadDatabase, LoadDataSource and SyncDataSource Methods, Synchronise will transfer all specified Data Sources in a single transaction rather than transferring each table in a separate transaction.

  This means that tables containing Foreign Keys which consist of Identity fields can be uploaded together with the relevant tables containing the Primary Key fields, and the Foreign Keys can be resolved at the back end and all records will be updated with the appropriate Identity values. If your tables include Identity field Foreign Keys, by default, Digitise Apps will automatically arrange and upload the tables in the required order to allow resolution of the Key fields at the remote end. You can specify the tables in any order within the up parameter or specify an empty string to rely on the Synch Direction Property to specify the Data Sources to be included in the synchronise.

   

  If you don't want the App Server to automatically specify the order in which the Data Sources should be processed, you can turn off automatic sorting using the DISABLE_TABLE_SORT option available with the SetApplicationOption Method. To turn off automatic sorting, call SetApplicationOption setting DISABLE_TABLE_SORT to "TRUE". The Data Sources will then be processed in the order in which you specify them in the up and/or down parameters.

  If either parameter is specified as an empty string, the Data Sources for that parameter will be automatically sorted as if DISABLE_TABLE_SORT were set to "FALSE".

  If you want to return to automatic sorting, call SetApplicationOption again setting DISABLE_TABLE_SORT to "FALSE".

  With automatic sorting disabled, where you have Identity Foreign Key fields, you will need to specify the relevant tables in a suitable order within the up parameter otherwise the Foreign Key values will not be updated correctly at the remote end. You should specify the Primary Key tables first followed by the tables with Foreign Key values referring to those Primary Keys.

• If you want Identity field Foreign Key values to be automatically updated in the device's local database as well as at the remote end, you must download the tables after the upload, otherwise you will need to manually update the Foreign Key fields on the device, from within a Script.

  Other types of Key field, such as GUIDs, will always have to be manually updated on the device after an upload. You can do this from within a Script.

• The Enable SQL Identify updates on Sync Property found under the Project Properties, allows you to automatically update Primary Key fields on the local device to match new values at the remote end after a data upload, without having to re-download the tables after the upload.

• If the parameters to this Method provide for tables to be uploaded and downloaded in the same transaction, all uploads will be performed first and then downloads will follow.

• When uploading Data to a remote data source, only records which are marked as modified will be uploaded. In addition, the Data Source must have a Primary Key defined, otherwise an error will be logged and the remote database will not be updated. If a record in the Target database has a Primary key which matches the Primary key in a record being uploaded, the existing record will be updated with the new data, otherwise a new record will be created in the Target database for the new data.

  You can specify multiple Primary Keys if necessary, in which case the combination of all specified Primary Keys must be unique for each record.

• Each data item in a Data Source has a Read-Only Property, which determines whether the data item in a local record can be overwritten. With Database Data Sources, where a column in a Data Source table is marked as being read-only, i.e., the Read-Only Property is set to True, data in that column will generally not be included in an upload and, hence, this may allow you to reduce the amount of data being transferred. For example, if you download data to a device for reference purposes only and this data will not be updated by the user, you can mark the column as read-only and thus exclude it from data uploads.

  By default, the Property is set to False.

  Note that Primary and Foreign Keys are always included in the data uploaded, whatever the value of the Read-Only Property, but Primary Keys, especially where the Identity Property is set to True, should usually be set to read-only, otherwise the remote database might reject an attempt to update it. Note, however, that the value of the Read-Only Property is honoured for Primary and Foreign Key fields in terms of whether local data can be overwritten.

• During an upload, each record which is successfully updated or created in the remote database, will have its modified record flag reset in the local database, so that it won't be uploaded by the next call to Synchronise or SyncDataSource, unless it is subsequently changed again before the next call.

  Data records, including new records, are marked as modified by calling UpdateCurrentRecord.

• If you attempt to upload a Custom Table, an error will be logged and the data will not be transferred.

• When downloading data to the device, the behaviour is determined by the setting of each individual table's Client-Side Conflict Resolution Property. If the Client-Side Conflict Resolution Property for a table is set to Server, the local table will be deleted and replaced with the data being downloaded. If the Client-Side Conflict Resolution Property is set to Client, any records in the local table marked as modified will not be overwritten or updated with data from the server. All other records will be updated with the downloaded data including deleting any records from the local table which are no longer present in the downloaded data and creating new local records for new records in the download.

  If a Data Source table doesn't have a Primary Key, the Client-Side Conflict Resolution Property is ignored and the local table will be deleted and replaced with the downloaded data.

• You can specify which records are to be downloaded for each Data Source table using the table's Filter Property for ADO Database Data Sources or its SQL Statement Property for Custom Tables, allowing you to provide a different SQL Select statement for each table if required.

  If the Data Source is a Custom Table, the SQL Statement Property should contain the full Select statement e.g. "SELECT * FROM table1 WHERE user = 'John'". The SELECT statement can start with SELECT or SELECT DISTINCT and columns can be referred to using the format <table>.<column> but <table>.* is not supported. The SELECT Statement must return the same number of columns as are defined in the Custom Table and in the order in which you want them to be mapped to the columns in the Custom Table.

  Otherwise, if the Data Source is an ADO Database Data Source, the Filter Property is used and should contain only a 'where' clause, excluding the word 'where', e.g. "user = 'John'". Columns can be referred to using the format <table>.<column> but <table>.* is not supported.

  In either case, when specifying your SQL Select statement you may want to specify the order in which records should be returned by including an ORDER BY clause, e.g. "SELECT * FROM table1 WHERE user = 'John' ORDER BY table1.userID".

  If the Filter or SQL Statement Property for a table is blank all records in that table will be downloaded.

  You can overwrite the value in a table's Filter or SQL Statement Property, or provide a SQL Select statement if the Filter or SQL Statement Property is blank, within your Scripts using the SetSelectString Scripting Method. SetSelectString allows you to create a list of Data Sources and specify a Select statement to be used to determine the records downloaded for each Data Source in the list. For Data Sources not included in the list, the Filter or SQL Statement Property will be used or, if this is blank, all records will be downloaded for that Data Source.

  Note:

  • The first call to SetSelectString resets the Data Source list.

  • Subsequent SetSelectString calls add Data Sources to this list.

  • Any calls to Synchronise, LoadDataSource or LoadDatabase will clear the Data Source list and these Methods will revert back to their default mode of operation, until another SetSelectString call is made.

  • When used with the Synchronise Method, SetSelectString does not determine which Data Sources will be downloaded, only which records will be selected.

    • You can also change a SQL statement specified in the Filter/SQL Statement Property for a Data Source within App Manager. This allows you to change the records to be selected without having to edit and republish your app. To do this display the Properties for the relevant app in App Manager and then use the Data Sources button.

• If the async parameter is set to "True":

  • The app does not pause whilst the transfer runs.

    In order for the transfers to operate in the background, the app must continue to run until the transfer is completed or cancelled. For async transfers, a progress bar is not displayed but users can continue to use the app. However, all tables included in the transfer, either up or down, will be locked until the synchronisation has completed or is cancelled to prevent users making changes to records which are in the process of being transferred. Records can still be read and their values displayed within the app, but the user will not be able to change or enter new data for the locked records.

  • You can check whether a table is locked using the IsDataSourceLocked Scripting Method and you can also check the progress and current state of a transfer or cancel the transfer from within a Script using the GetTransactionProgress, GetTransactionState and CancelTransaction Scripting Methods, respectively.

  • On Apple devices, the Enable Background Fetch option determines whether a transfer can continue when the app is moved into the background - see Build a Single App Standalone App and Build a Pre-Configured Digitise Apps Client for more information about this Property.

  • If a transfer is interrupted for any reason, e.g. loss of signal, the Digitise Apps Client will automatically retry (at increasing intervals) until the transfer completes or is cancelled from within a Script.

  • When an asynchronous transaction completes, the OnAsyncCompletion Event will be triggered. You can use this Event to notify users that the transaction has finished and to check for errors.

  • If you initiate an asynchronous transfer within the OnExit Event, the transfer will run but it will automatically be switched to synchronous mode to prevent the app closing before the transfer is completed. In addition, the Client will automatically call the SetApplicationOption Method and set the PROGRESS_MODE option to INDETERMINATE to display the busy indicator whilst the transfer is in progress and call SetDataErrorOff so that if any errors occur the transfer will fail silently.

  • If an asynchronous transfer is in progress when a Script calls ExitApplication, the OnExit Event will be triggered as usual allowing the shutdown to be aborted or the transfer to be cancelled. If a user attempts to shutdown an app from the app's Home screen or the Digitise Apps Client's applications list, the OnExit Event will also be triggered but you cannot cancel the shutdown by returning -1 from the OnExit Script as you can when calling ExitApplication. You can cancel the transfer using CancelTransaction in the OnExit Script or when the OnExit Script ends the transaction will be cancelled. Calling ExitClient will also cancel a transfer. In all cases, the OnAsyncCompletion Event will be triggered with a success value of "False".

  • Each ADO Database Data Source has a Use SQL Transaction Property. This Property allows you to determine whether any problems inserting or creating records when uploading data from the device to the remote Target database should result in the transfer being rolled back.

    If the Property is set to True any such problems will result in all changes being rolled back for that Data Source and the data tables will be returned to the state they were in before the transfer started. If set to False, the transfer will complete and all changes made successfully will be committed, records in the local database which couldn't be updated or created at the remote end will remain marked as modified in the local table.

    In either case any such errors will be logged in the standard audit log and reported back to the Digitise Apps Client or Standalone App and can be accessed from within your Scripts using the GetNumSyncErrors, GetSyncErrorDataSource, GetSyncErrorDescription and GetSyncErrorRecordIndex Methods, e.g. within the OnAsyncCompletion Event. If set to True, the transfer does not stop if a record fails to update or be inserted; rather the transfer continues until all records have been attempted after which, if there have been any failures, all the changes are rolled back. This means that all potential issues are reported back to the Digitise Apps Client and not just the first one found. If a roll-back is performed, an error will be generated for each record indicating whether the insert or update failed for that particular record or the record was rolled back.

   

  If the async parameter is set to "False":

  • Data transfers will pause the app until the transfers complete and the user cannot interact with the app whilst the transfers are in progress.

  • A progress bar will be displayed, including a cancel button allowing the user to terminate the transfer if required. If a user cancels the transfer, the calling Script will continue from the next line after the call to Synchronise. The SetApplicationOption Method allows you to reduce or turn off the messages displayed with the progress bar or to replace it with the device's standard busy indicator instead. It also allows you to disable/re-enable the ability to cancel the download.

  • Synchronous transfers do not trigger an Event on completion.

  • The Use SQL Transaction Property discussed above also affects synchronous transfers.

  • Errors will be logged in the standard audit log and reported back to the Digitise Apps Client or Standalone App and can be accessed from within your Scripts using the GetNumSyncErrors, GetSyncErrorDataSource, GetSyncErrorDescription, GetSyncErrorRecordIndex and GetLastDataError Methods.

• You cannot make a second call to Synchronise, nor call one of the other data transfer Methods, LoadDataSource, LoadDatabase or SyncDataSource, whilst an asynchronous transfer is in progress.

• If the App Server is unable to send the result of the transfer back to the Digitise Apps Client because the connection between the Client and the Server fails, you may be able to use the IsRetrySyncAvailable and RetrySync Methods to obtain the results once the connection is re-established - see the description of the IsRetrySyncAvailable Method for details.

• This Method is not relevant for use with Custom Views.

• On Android devices, note the following potential issues relating to large data objects, particularly photographs:

  • The uploading of records that contain multiple photo/video fields may fail due to a limitation in SQLite where the records cannot be read in their entirety from the database when the cumulative size of the data that they contain is over a certain size. This limit is undefined but appears to be tied to the version of Android and the amount of memory the device has available.

  • When downloading large binary fields (i.e. photos or videos) on lower power/memory devices the Digitise Apps Client may fail to download some large bitmaps/videos into the application database. An Out Of Memory error message will be displayed. The overall download should complete but some records may not contain the downloaded image/video data, having Null values in the columns where the Out Of Memory issue occurred. This problem may occur where you are trying to download photos/videos taken on one device, with a higher megapixel camera, to another less powerful device.

 

• We recommend that you take care when using Synchronise to perform background data transfers, especially if you consider using this Method within a timer to perform automatic transfers. Transfer requests being initiated too often and/or from large numbers of users simultaneously could affect the performance of your App Server and thus the rate of individual transfers.